olem module

The olem module gives access to all the features of OLEM: movements, LEDs, sensors, display, game messages... Import it at the top of your game with import olem.

Generated from version ad8133d of the game development kit.

Movement

Constants

Constant	Value	Description
MOVE_CORR_X_MASK	1	Correction along the x axis, based on the lines of the tiles.
MOVE_CORR_Y_MASK	2	Correction along the y axis, based on the lines of the tiles.
MOVE_CORR_DISTANCE_MASK	4	Correction of the travelled distance, based on the spacing between the lines of the tiles. Requires MOVE_CORR_X_MASK.
MOVE_CORR_IWJ_MASK	32
MOVE_CORR_ISS_MASK	64
MOVE_CORR_MSAFE_MASK	128	Refuse movements that would make OLEM fall off the board or table.

move(x, y, rotation)

Move OLEM by the requested amount in cartesian space, relative to its current position.

Returns immediately, use wait_stop_moving() to wait for the end of the movement.

Parameter	Description
x	translation along the x axis in mm
y	translation along the y axis in mm
rotation	rotation in degrees

move_to(x, y, orientation)

Move OLEM to a position in cartesian space, relative to its position at startup or at the last reset_position().

Returns immediately, use wait_stop_moving() to wait for the end of the movement.

Parameter	Description
x	position along the x axis in mm
y	position along the y axis in mm
orientation	orientation in degrees

wait_stop_moving()

Block until OLEM stops moving.

The wait ends if the game is stopped.

stop_moving()

Stop the current movement.

turn(rotation)

Turn OLEM on itself by the requested angle.

Returns immediately, use wait_stop_moving() to wait for the end of the rotation.

Parameter	Description
rotation	rotation in degrees

turn_to(orientation)

Turn OLEM on itself to the requested orientation.

Returns immediately, use wait_stop_moving() to wait for the end of the rotation.

Parameter	Description
orientation	orientation in degrees

move_polar(distance, direction, rotation)

Move OLEM by the requested amount in polar space, relative to its current position.

Returns immediately, use wait_stop_moving() to wait for the end of the movement.

Parameter	Description
distance	distance to travel in mm
direction	direction of the movement in degrees
rotation	rotation in degrees

move_to_polar(distance, direction, orientation)

Move OLEM to a position given in polar space, relative to its position at startup or at the last reset_position().

Returns immediately, use wait_stop_moving() to wait for the end of the movement.

Parameter	Description
distance	distance from the origin in mm
direction	direction from the origin in degrees
orientation	orientation in degrees

move_towards(direction)

Move OLEM in a direction until stop_moving() is called.

Parameter	Description
direction	direction in degrees, relative to OLEM's current orientation

set_move_speed(speed)

Set the speed of the movements requested after this call.

The default speed is 1.0.

Parameter	Description
speed	fraction of the maximum speed, from 0.0 to 1.0

get_move_speed()

Returns: speed set with set_move_speed(), from 0.0 to 1.0

get_position_x()

Returns: position along the x axis in mm, relative to the position at startup or at the last reset_position()

get_position_y()

Returns: position along the y axis in mm, relative to the position at startup or at the last reset_position()

get_orientation()

Returns: orientation in degrees, from 0 to 359

get_orientation_absolute()

Unlike get_orientation(), the orientation is not brought back between 0 and 359: it keeps counting full turns and can be above 360 or negative.

Returns: orientation in degrees, as an integer

reset_position()

Stop the current movement and use the current position as the new origin: position (0, 0) and orientation 0.

is_moving()

Returns: True if OLEM is moving, False otherwise

center_on_rotate(angle)

Re-center OLEM on its tile: OLEM turns on itself and uses the lines of the tile seen by its floor sensors to correct its position.

Returns immediately. Has no effect if a centering is already running.

Parameter	Description
angle	rotation to perform in degrees, 90 is recommended

move_correction_enable(mask)

Enable automatic corrections of the movements.

Parameter	Description
mask	corrections to enable, combine MOVE_CORR_* constants with |

move_correction_disable(mask)

Disable automatic corrections of the movements.

Parameter	Description
mask	corrections to disable, combine MOVE_CORR_* constants with |

Extension module

Constants

Constant	Value	Description
LOW	0	Low level of a GPIO output.
HIGH	1	High level of a GPIO output.
EXTMOD_GPIO1	1	Pin P1 of the extension slots.
EXTMOD_GPIO2	2	Pin P2 of the extension slots.
EXTMOD_GPIO	0	GPIO mode: P1 and P2 are digital outputs.
EXTMOD_I2C	1	I2C mode: P1 is SCL and P2 is SDA.
EXTMOD_PWM	2	PWM mode: P1 and P2 output PWM signals.

extmod_mode_set(mode)

Initialize the extension slots in the given mode. Only one mode can be used at a time.

Parameter	Description
mode	EXTMOD_GPIO, EXTMOD_I2C or EXTMOD_PWM

extmod_gpio_set(gpio, value)

Set the output level of a pin. Requires the EXTMOD_GPIO mode, see extmod_mode_set().

Parameter	Description
gpio	EXTMOD_GPIO1 or EXTMOD_GPIO2
value	LOW or HIGH

extmod_pwm_set(gpio, period, compare_value)

Set the PWM signal of a pin. Requires the EXTMOD_PWM mode, see extmod_mode_set().

Parameter	Description
gpio	EXTMOD_GPIO1 or EXTMOD_GPIO2
period	period of the signal in ms, as an integer. With 0 the output stays LOW.
compare_value	time the signal stays HIGH in each period in ms, as an integer

extmod_i2c_read(addr, length)

Read bytes from a device on the I2C bus. Requires the EXTMOD_I2C mode, see extmod_mode_set().

Parameter	Description
addr	address of the device
length	number of bytes to read

Returns: list of the bytes read, as integers, or an empty list if the read failed

extmod_i2c_write(addr, data)

Write bytes to a device on the I2C bus. Requires the EXTMOD_I2C mode, see extmod_mode_set().

Parameter	Description
addr	address of the device
data	list of the bytes to write, as integers from 0 to 255

Returns: 0 on success, an error code otherwise

LEDs

Constants

Constant	Value	Description
LED0	1	Mask of LED 0.
LED1	2	Mask of LED 1.
LED2	4	Mask of LED 2.
LED3	8	Mask of LED 3.
LED4	16	Mask of LED 4.
LED5	32	Mask of LED 5.
LEDALL	63	Mask of all the LEDs.

led_on(mask, hexcolor)

Turn LEDs on with a fixed color.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL
hexcolor	color as a "#RRGGBB" string

led_off(mask)

Turn LEDs off.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL

led_pulse(mask, period, hexcolor)

Make LEDs pulse: they fade smoothly in and out of the color.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL
period	pulse period in ms
hexcolor	color as a "#RRGGBB" string

led_blink(mask, period, hexcolor)

Make LEDs blink: they switch between the color and off.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL
period	blink period in ms
hexcolor	color as a "#RRGGBB" string

led_transition(mask, duration, hexcolor)

Change the color of LEDs smoothly, from their current color to the new one.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL
duration	duration of the transition in ms
hexcolor	new color as a "#RRGGBB" string

led_flicker(mask, intensity)

Add random noise to the color of LEDs, on top of their current effect: it can be used while LEDs are pulsing for example.

At each refresh, a random value of up to +/- half of the intensity is added to each color component. For example led_flicker(LEDALL, "#100020") adds up to +/- 8 to the red and up to +/- 16 to the blue of all the LEDs.

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL
intensity	noise intensity of each component as a "#RRGGBB" string

led_flicker_off(mask)

Stop the noise added with led_flicker().

Parameter	Description
mask	LEDs to use, combine LED0 to LED5 with |, or use LEDALL

led_shifting(period, direction)

Periodically move the configuration of each LED to its neighbour, so that the LED pattern turns around OLEM.

Parameter	Description
period	time between two shifts in ms
direction	0 to shift from left to right, 1 from right to left

led_shifting_off()

Stop the shifting started with led_shifting().

Timing

delay_ms(delay)

Wait for the given duration. The game can still be stopped during the wait.

Parameter	Description
delay	duration in ms

get_time_ms()

Returns: time since OLEM started in ms

Side sensors

Constants

Constant	Value	Description
FRONT	0	Front side of OLEM.
RIGHT	1	Right side of OLEM.
BACK	2	Back side of OLEM.
LEFT	3	Left side of OLEM.
FRONT_MASK	1	Bit of the front side in a side mask.
RIGHT_MASK	2	Bit of the right side in a side mask.
BACK_MASK	4	Bit of the back side in a side mask.
LEFT_MASK	8	Bit of the left side in a side mask.

ir_side_get_sensor_value(sensor)

Get the signal of a side sensor. Side sensors see objects up to about 150 mm away.

Parameter	Description
sensor	FRONT, RIGHT, BACK or LEFT

Returns: filtered signal in ADC units (LSB), it increases when an object gets closer

ir_side_get_sensor_percent(sensor)

Get the signal of a side sensor as a percentage.

Parameter	Description
sensor	FRONT, RIGHT, BACK or LEFT

Returns: from 0 when nothing is detected to 100 when an object is very close

ir_side_is_hand_present(side)

Check if a hand is in front of a side sensor. A hand gives a weaker signal than an obstacle.

Parameter	Description
side	FRONT, RIGHT, BACK or LEFT

Returns: True if a hand is detected, False otherwise or if side is not valid

ir_side_is_obstacle_present(side)

Check if an obstacle is in front of a side sensor. An obstacle gives a stronger signal than a hand.

Parameter	Description
side	FRONT, RIGHT, BACK or LEFT

Returns: True if an obstacle is detected, False otherwise or if side is not valid

ir_side_get_hand_mask()

Returns: mask with the bit of each side where a hand is detected, test it with FRONT_MASK, RIGHT_MASK, BACK_MASK and LEFT_MASK

ir_side_get_obstacle_mask()

Returns: mask with the bit of each side where an obstacle is detected, test it with FRONT_MASK, RIGHT_MASK, BACK_MASK and LEFT_MASK

ir_side_get_number_of_hands()

Returns: number of sides where a hand is detected, from 0 to 4

ir_side_set_filter(value)

Set the filter applied to the side sensors. A higher value makes them slower to react but more stable. The default value is 5.

Parameter	Description
value	filter coefficient, 1 or more

Floor sensors

ir_floor_get_sensor_value(sensor)

Get the signal of a floor sensor. The signal is the strongest on a white surface and the weakest on a black surface or when there is no floor.

OLEM has 6 floor sensors, numbered clockwise: 0 front left, 1 front right, 2 right, 3 back right, 4 back left, 5 left.

Parameter	Description
sensor	index of the sensor, from 0 to 5

Returns: signal in ADC units (LSB), or 0 if sensor is not valid

ir_floor_is_floor_present(side)

Check if there is floor under a side of OLEM, to detect the edge of the board or table.

Parameter	Description
side	FRONT, RIGHT, BACK or LEFT

Returns: True if the floor is detected, False otherwise or if side is not valid

ir_floor_get_void_count()

Returns: number of floor sensors that do not see the floor

Top sensor

ir_top_is_hand_present()

Check if a hand is above the top sensor. It can be used as a button for the players.

Returns: True if a hand is detected, False otherwise

ir_top_get_sensor_value()

Returns: filtered signal of the top sensor in ADC units (LSB), it increases when a hand gets closer

ir_top_get_sensor_percent()

Returns: signal of the top sensor, from 0 when nothing is detected to 100 when a hand is very close

Game messenger

gmsg_wait_for_message()

Wait for a message from the mobile app or the Command Center. The game can still be stopped during the wait.

Received messages are kept in a queue of up to 20 messages.

Returns: the oldest message received

gmsg_wait_for_message_timeout(timeout)

Wait for a message from the mobile app or the Command Center, for a limited time.

Parameter	Description
timeout	maximum time to wait in ms

Returns: the oldest message received, or an empty string if no message arrived in time

gmsg_send_message(message)

Send a message to the mobile app or the Command Center.

Parameter	Description
message	text of up to 100 bytes. Do not use the alert character "\a".

gmsg_reset_queue()

Delete the received messages that were not read yet.

gmsg_get_message()

Get the oldest received message, without waiting.

Returns: the oldest message received, or an empty string if there is none

gmsg_get_waiting_message_count()

Returns: number of received messages that were not read yet

Display

Constants

Constant	Value	Description
FONT_DEFAULT	0	Default font size.
FONT_SMALL	1	Small font size.
FONT_BIG	2	Big font size.
ALIGN_LEFT	0	Text aligned on the left.
ALIGN_CENTER	1	Text centered.
ALIGN_RIGHT	2	Text aligned on the right.

class lv_obj

Type of the screen objects returned by the display functions, such as display_text() or display_button(). It cannot be created directly.

The screen is 320 x 240 px, (0, 0) is its top left corner.

display_text(text, font_size, align)

Create a text object.

Parameter	Description
text	text to display
font_size	FONT_SMALL, FONT_DEFAULT or FONT_BIG
align	ALIGN_LEFT, ALIGN_CENTER or ALIGN_RIGHT

Returns: the text object

display_button(text, event_id)

Create a button. When it is pressed, event_id is added to the event queue, see display_get_event().

Parameter	Description
text	text of the button
event_id	integer identifying the button in the event queue, 0 is not allowed

Returns: the button object

display_img(file_name)

Create an image object from a file. Images must be converted with the LVGL v8 image converter, in binary RGB565.

Parameter	Description
file_name	path of the image file, relative to the assets folder of the game

Returns: the image object

display_img_button(file_name)

Create a clickable image object from a file. Use display_add_event_cb() to choose the event it triggers.

Parameter	Description
file_name	path of the image file, relative to the assets folder of the game

Returns: the image object

display_qr_code(size, data)

Create a QR code object, black on white.

Parameter	Description
size	width and height in px
data	text encoded in the QR code

Returns: the QR code object

display_set_qr_code_data(lvgl_obj, data)

Change the text encoded in a QR code object.

Parameter	Description
lvgl_obj	QR code object created with display_qr_code()
data	new text to encode

display_add_event_cb(lvgl_obj, event_id)

Make an object clickable: when it is clicked, event_id is added to the event queue, see display_get_event().

Parameter	Description
lvgl_obj	object to make clickable
event_id	integer identifying the object in the event queue, 0 is not allowed

display_del(lvgl_obj)

Delete an object from the screen. It must not be used afterwards.

Parameter	Description
lvgl_obj	object to delete

display_del_all()

Delete all the objects from the screen. The background color is kept.

display_center(lvgl_obj)

Center an object on the screen.

Parameter	Description
lvgl_obj	object to center

display_set_pos(lvgl_obj, x, y)

Move an object on the screen.

Parameter	Description
lvgl_obj	object to move
x	position of its left side in px
y	position of its top side in px

display_get_pos(lvgl_obj)

Parameter	Description
lvgl_obj	displayed object

Returns: position of the object as a list [x, y] in px

display_get_size(lvgl_obj)

The object must already be drawn on screen, see display_wait_for_next_frame().

Parameter	Description
lvgl_obj	displayed object

Returns: size of the object as a list [width, height] in px

display_set_size(lvgl_obj, width, height)

Resize an object. Images are not scaled, only their container is resized.

Parameter	Description
lvgl_obj	object to resize
width	new width in px
height	new height in px

display_set_text(lvgl_obj, text)

Change the text of a text object.

Parameter	Description
lvgl_obj	text object created with display_text()
text	new text to display

display_set_img_src(lvgl_obj, file_name)

Change the image of an image object.

Parameter	Description
lvgl_obj	image object created with display_img()
file_name	path of the new image file, relative to the assets folder of the game

display_move_to_foreground(lvgl_obj)

Draw an object above all the others.

Parameter	Description
lvgl_obj	object to move

display_move_to_layer(lvgl_obj, index)

Choose in which order an object is drawn.

Parameter	Description
lvgl_obj	object to move
index	0 is the background, the foreground is the number of objects on screen minus 1

display_wait_for_next_frame()

Wait until the next frame is drawn on screen.

display_mutex_take()

Prevent the screen from being redrawn, so that several objects can be created and configured before they appear. The screen is frozen until display_mutex_give() is called.

display_mutex_give()

Allow the screen to be redrawn again after display_mutex_take().

display_get_event()

Get the oldest event triggered by a button or a clickable object, without waiting.

Returns: id of the oldest event, or 0 if there is none

display_clear_events()

Delete the events that were not read yet.

display_wait_for_event()

Wait for an event triggered by a button or a clickable object. The game can still be stopped during the wait.

Returns: id of the event

display_wait_for_event_timeout(timeout)

Wait for an event triggered by a button or a clickable object, for a limited time.

Parameter	Description
timeout	maximum time to wait in ms

Returns: id of the event, or 0 if no event happened in time

display_set_bkg_color(color)

Change the background color of the screen.

Parameter	Description
color	color as a "#RRGGBB" string

display_set_text_color(lvgl_obj, color)

Change the color of a text object.

Parameter	Description
lvgl_obj	text object created with display_text()
color	color as a "#RRGGBB" string

display_set_default_text_color(color)

Change the color of the text objects created after this call.

Parameter	Description
color	color as a "#RRGGBB" string

display_set_backlight(value)

Set the brightness of the screen.

Parameter	Description
value	brightness from 0 to 100, other values are clamped

Audio

audio_play_file(file_name)

Play an audio file. The sound being played, if any, is stopped. Returns immediately, see audio_wait_end_of_playback().

Parameter	Description
file_name	path of the audio file, relative to the assets folder of the game

audio_is_playing()

Returns: True if a sound is being played, False otherwise

audio_wait_end_of_playback()

Wait for the end of the sound being played. Returns immediately if no sound is played. The game can still be stopped during the wait.

audio_stop()

Stop the sound being played.

audio_pause()

Pause the sound being played, see audio_resume().

audio_resume()

Resume the sound paused with audio_pause().

audio_mute(mute)

Mute or unmute the sound.

Parameter	Description
mute	True to mute, False to unmute

audio_volume_set(volume)

Set the volume of the game sounds. The volume chosen in OLEM's settings still applies on top of it.

Parameter	Description
volume	from 0.0 (muted) to 1.0 (maximum)

audio_volume_get()

Returns: volume set with audio_volume_set(), from 0.0 to 1.0

audio_volume_enable(enable)

Enable or disable the volume set with audio_volume_set().

Parameter	Description
enable	True to enable, False to disable

audio_white_noise_enable(enable)

Start or stop playing white noise.

Parameter	Description
enable	True to start, False to stop

audio_white_noise_amplitude_set(amplitude)

Set the loudness of the white noise.

Parameter	Description
amplitude	from 0.0 to 1.0, fraction of the maximum amplitude

audio_white_noise_amplitude_get()

Returns: amplitude set with audio_white_noise_amplitude_set(), from 0.0 to 1.0

NFC

nfc_enable()

Start detecting NFC tags. The reader is under OLEM, between the front wheels. Only NTAG type 2 tags (ISO/IEC 14443A, sold as NTAG2xx) are supported.

nfc_disable()

Stop detecting NFC tags.

nfc_is_enabled()

Returns: True if NFC detection is enabled, False otherwise

nfc_get_number_of_cards_waiting()

Returns: number of detected tags that were not read yet with nfc_get_card_data()

nfc_get_card_data()

Get the data of the oldest detected tag that was not read yet.

Returns: text stored on the tag, or an empty string if there is no tag waiting

System

get_sys_language()

Returns: language chosen in OLEM's settings: "EN" for English, "FR" for French

get_power_button_state()

Returns: 0 while the power button is pressed, 1 otherwise